<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Passing Goals and Control to ECLiPSe
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot019.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot021.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc37">5.4</A>&nbsp;&nbsp;Passing Goals and Control to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP></H2>
The control flow between Tcl and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is conceptually thread-based.
An ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal is executed by using the <B>ec_rpc</B> mechanism. The
goal is posted from Tcl, and control is transferred automatically to
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to allow the goal to be executed. Control can also be explicitly
transferred to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> using <B>ec_resume</B>. Furthermore, handler goals
can be implicitly invoked on I/O operations on queues (this is described in
more detail in section&nbsp;<A HREF="embroot021.html#tclembedqueues">5.5</A>, with implicit
transfer of control.<BR>
<BR>
The related commands are the following:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default81"></A><B>ec_rpc <I>goal ?format?</I></B><DD CLASS="dd-description"><BR>
Remote ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> predicate call.
 It calls goal in the default module. The goal should be simple
	in the sense that it can only succeed, fail or throw.
	It must not call
	<A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default82"></A>.
 Any choicepoints the goal leaves will be discarded.<BR>
<BR>
	Unlike <B>ec_resume</B>, calls to <B>ec_rpc</B> can be nested
	and can be used from within Tcl queue event handlers.<BR>
<BR>
	If no format argument is given, the goal is assumed to be in
	ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> syntax. If a <I>format</I> argument is provided,
	the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal is constructed from <I>goal</I> and <I>format</I>,
	according to the conversion rules explained in section <A HREF="embroot024.html#secexdrtcl">5.8</A>.<BR>
<BR>
On success, <B>ec_rpc</B> returns the (possibly more instantiated)
	goal as a Tcl data structure, otherwise "fail" or "throw" respectively.<BR>
<BR>
	This is the recommended way of executing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code from Tcl,
	and passing the results back (via output arguments) to Tcl.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default83"></A><B>ec_running</B><DD CLASS="dd-description"><BR>
	checks whether an asynchronous ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread is still running.
	If that is the case, the only interface function that can be
	invoked reliably is <B>ec_post_event</B>.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default84"></A><B>ec_resume <I>?async?</I></B><DD CLASS="dd-description"><BR>
resume execution of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine: All posted events
 and goals will be executed. The return value will be "success"
 if the posted goals succeed, "fail" if the goals fail, and
	"yield" if control was transferred because of a
 <A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default85"></A>
 predicate call in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code. No parameters can be passed.<BR>
<BR>
	If the <I>async</I> parameter is 1 (default 0), the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
	execution is resumed in a separate thread, provided this is
	supported by the operating system. The effect of this is that
	Tcl/Tk events can still be handled while ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is
	running, so the GUI does not freeze during computation. 
	However, only one ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread can be running at any
	time, so before doing another call to <B>ec_resume</B>, <B>	ec_handle_events</B> or <B>ec_rpc</B> one should use <B>	ec_running</B> to check whether there is not a thread still running. <BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default86"></A><B>ec_flush <I>?stream_nr?
	?nbytes?</I></B><DD CLASS="dd-description"><BR>
flushes the Tcl end of a to-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> queue (see
 section&nbsp;<A HREF="embroot021.html#tclembedqueues">5.5</A>) that has the
 ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stream number <I>stream_nr</I>. Control is then
 briefly transferred to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> so that any events that are raised
 can be handled. Afterwards the control is passed back to Tcl.
 <I>nbytes</I> is a dummy argument
 and is provided for compatibility with the Tcl remote interface
 only.</DL>
<HR>
<A HREF="embroot019.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot021.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
